home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 (Alt) / MACD 5.bin / www / ludzie / txf / progs / savenames.lha / SaveNames1.5 / SaveNames.doc < prev    next >
Encoding:
Text File  |  1996-12-12  |  15.0 KB  |  357 lines
  1.  
  2.  
  3.  Copyright (why not...)
  4.  ----------------------
  5.  
  6.  SaveNames v1.4 software and documentation are copyrighted © 1995-1996
  7.  by Marcin Orlowski. All Rights Reserved.
  8.  
  9.  Update to v1.4 is made by Tadek Knapik. Thanks.
  10.  
  11.  
  12.  Distribution (pirate or die!)
  13.  -----------------------------
  14.  
  15.  Freely distributable in complete archive with following files included:
  16.  
  17.  SaveNames.c         - source code
  18.  SaveNames.c.info    - source icon
  19.  SaveNames.doc       - this documentation
  20.  SaveNames.doc.info  - documentation icon
  21.  SaveNames.man       - this documentation in UNIX's man format
  22.  SaveNames           - Amiga executable
  23.  SaveNames.info      - Amiga executable icon
  24.  SD!.displayme       - our BBS info
  25.  
  26.  
  27.  Disclaimer (as always :)
  28.  ------------------------
  29.  
  30.  No responsibility or liability will be accepted for any damage that
  31.  may appear to have resulted from use of this program. All use is at
  32.  your own risk. The software is provided "as is" without any warranty
  33.  implied or otherwise to the fitness or accuracy of the software and
  34.  documentation. The author reserves the right to update the software
  35.  and/or documentation without notice.
  36.  
  37.  
  38.  Usage (what is it!?)
  39.  --------------------
  40.  
  41.  Some people (like me) are forced to use pee-cee machines to transfer
  42.  files from internet to my Amiga (it doesn't mean I've bought a pc
  43.  for my own! I use (big word:) it only at my technical university).
  44.  As you all know, no one needs more chars to name his files than 8.3,
  45.  which seems to be a 'professional filename format'. Any other, longer
  46.  names are obsolete and should be forbidden. Unfortunately both Amiga
  47.  and Unix based machines use longer names for their files, so
  48.  transfering files between those platforms via pc causes 90% of name
  49.  (mainly dots :) to be eaten by pc. So I decided to cure this.
  50.  SaveNames is the medicine against. What does it do? Lets say, you want
  51.  to transfer some files stored in directory 'MyFiles' on your Unix
  52.  account to Amiga via pc floppies. Files use 'obsolete' names:
  53.  
  54.                      kickstart
  55.                      KICKdisk.info
  56.                      kickstart.info
  57.  
  58.  So before you start to copy them to disk type:
  59.  
  60.                      SaveNames C MyFiles
  61.  
  62.  and names of all files in this directory are converted ('C' means
  63.  'CODE' and may be lowercase or mixedcase) to less than 8 chars (suffix
  64.  'PCP' (pc protection :) will also be added to allow you easily detect
  65.  those files, or automate decoding e.g. via DOpus FileClass. If you use
  66.  DOpus set class checking to: "MATCHNAME WFMHFile.idx OR MATCHNAME #?.pcp"
  67.  and operation to "(AmigaDos) SaveNames D {s}" and you will decode files
  68.  by doubleclick.). Phew, you said? No big deal? pc does it itself! Bet it
  69.  doesn't. If you look in your 'MyFiles' drawer you'll find the new file
  70.  named 'WFMHFile.idx' looking like that:
  71.  
  72.                      7204094 kickstart
  73.                      720704c KICKdisk.info
  74.                      72085c4 kickstart.info
  75.  
  76.  Got it? Yes! Those data are used to restore filenames after whole
  77.  transfer on destination machine. How to do this? Copy transfered files
  78.  from pc disks to one directory on your Amiga disk (e.g. 'MyFilesToo')
  79.  and type:
  80.  
  81.                      SaveNames D MyFilesToo
  82.  
  83.  This time command 'D' means 'Decode'. Program opens file index
  84.  described below and renames all known (stored in index) files back
  85.  to theirs original names. Simple? Yes, it is. And it works too!
  86.  
  87.  NOTES: Command 'D' has special, expanded mode, activating by '-'
  88.         as command prefix: '-D'. See 'Technical Info' chapter to find
  89.         out what this feature is for.
  90.  
  91.         While names coding SaveNames shows you estimated number of disks
  92.         you will need to store all your crypted files on. If you want
  93.         do this calculation without main code process use '-C' command
  94.         instead of 'C'
  95.  
  96.  Since version 1.4 SaveNames has ability to split large files into smaller
  97.  pieces. For what? Imagine you have just downloaded Aminet Index (as I had).
  98.  It's big, isn't it? Of course I compressed it, but it was still more KBytes
  99.  than PC DD diskette (however it would fit on Amiga DD harmless :-).
  100.  SaveNames can help you manage it. Just type:
  101.  
  102.                      SaveNames C MyFiles SplitSize
  103.  
  104.  which means you want files larger than <SplitSize> bytes to be parted
  105.  into smaller pieces (with size defined as SplitSize). In result you get:
  106.  
  107.                      78003582.pc0
  108.                      78003582.pc1
  109.                      78003582.pc3
  110.                      ............
  111.                      ............
  112.                      78003582.p74
  113.  
  114.  while WFMHFile.idx still holds only one entry with '78003582.pcp'.
  115.  Joining is done during DECODing automatically and fully transparently
  116.  whenever needed. No need for extra switches and keywords to be used.
  117.  
  118.  Thanks to this option you don't have to use another program for splitting.
  119.  SaveNames does everything, and does it in a convenient way, not leaving
  120.  you with partial files after rejoining, like some splitters (unless an
  121.  error occures, of course).
  122.  
  123.  Note: To split a file, you need spare space equal to size of splitting
  124.  file (obvious). To join it back it, you need spare space of equal to 
  125.  SplitSize you used while splitting. Be careful on low storage (disk full).
  126.  Splitting may take a while...
  127.  
  128.  You can use any SplitSize you want but SaveNames assumes you know what you
  129.  are doing so therefore it got no superb dumb filters built-in and is not
  130.  idiot-proof. Every file can be maximally splited into 999 due to pee-see
  131.  poor filename scheme. This should be enough for almost all cases (hey,
  132.  you're not downloading encyclopedia everyday, are you?). Instead
  133.  of typing '720000' or '1440000' as SplitSize you can use 'DD' or 'HD'
  134.  equivalents (case insensitive).
  135.  
  136.  
  137.  Requirements
  138.  ------------
  139.  
  140.  Something with Intel outside, few bytes of free memory, files to eat,
  141.  2 busty babes and 1 big beer.
  142.  
  143.  
  144.  Technical info (sounds soooo wise... :)
  145.  ---------------------------------------
  146.  
  147.  Portability is base idea of this project, so SaveNames is written in
  148.  plain ANSI C and may be simply compiled on any machine. If you find any
  149.  problems, let me know! And do not compile it on pc - it doesn't have any
  150.  sense... :)
  151.  
  152.  Unfortunately small changes, as always, have to be done before you run
  153.  the compiler, so look into the source, and select your platform (for
  154.  now AMIGA, UNIX (being honest IRIX) and LINUX is checked and supported.
  155.  If you port it to Mac world let me know and send changes to me (in this
  156.  case please do only small GUI). AMIGA side was tested on my A4000, UNIX
  157.  platform was tested on SILICON GRAPHICS' IRIS INDIGO and HP. LINUX side
  158.  was tested on... LINUX side :-)
  159.  
  160.  Name encoding is done in two passes. 1st pass - scanning directory
  161.  and building coded names, 2nd pass renaming files and writting
  162.  index file. It has to be done this way, because scanning directory
  163.  while it is changing, may (and in 99% it does) put the program in the
  164.  infinite loop. Sometimes we may also miss some files. Decoding is done
  165.  in one pass.
  166.  
  167.  Starting to decode, program tries to read index file first. First it
  168.  tries to open file named 'WFMHFile.idx'. If file couldn't be found,
  169.  it tries to open file again, with name in lowercase and if it fails
  170.  to, the last try use uppercased name. This is important mainly for
  171.  Unix side, because Unix is case-sensitive. So if you transferred
  172.  your files via pc, the names may be 'fixed' to lower or uppercase.
  173.  While decoding, program may do the same trick with files to decode,
  174.  but this feature is defaulty off, which means that only one try is
  175.  attemped, and filenames are supposed to be exactly the same as while
  176.  coding. Use '-D' instead of 'D' to turn this mode on.
  177.  
  178.  You may convert as many file names as you wish, because there's no
  179.  static arrays, but dynamicaly build list. You are only limited by your
  180.  memory. To code 1000 names you will need, on Amiga, about 266KB. Why
  181.  only 266KB? Because every name is stored in a list's entry containing
  182.  pointer to next entry (on 32bit machines it takes 4 bytes), converted
  183.  name (12 chars + trailing zero) and original file name. The size of last
  184.  entry depends on your system. In your system includes, you will find
  185.  definition of MAXNAMELEN, which limits max length of filename. On Amiga
  186.  it's set to 255 chars. For now it's too much, because you cannot use names
  187.  longer than 30 chars (because there's no more free bytes on disk block).
  188.  So if you are REALLY out of memory, you may change this by hand (see
  189.  included source). Safe value is 108, because system structure
  190.  FileInfoBlock reserves exactly 108 bytes for filename. You may save then
  191.  few bytes. E.g. for those 1000 files mentioned above, with MAXNAMELEN
  192.  set to 30 you will save 248KB, with MAXNAMELEN set to 108, only :) 145
  193.  KB but think what are you doing! You probably never code more than 100
  194.  names in one session and you surely do not use A1000 with 256 KB RAM. So
  195.  better leave MAXNAMELEN alone...
  196.  
  197.  You may ask: How do you code filenames to those weird numbers, pal?
  198.  I answer: I do not code it at all! I'm just copying file's own INode
  199.  (it's kind of FileHandle on Unix machines). Because all filesystems
  200.  use almost the same algorithms, it also use INodes without any tricks
  201.  (maybe pc does it different, but who cares pc?). Sometimes it is
  202.  called INode, sometimes FileHandle and sometimes BlahBlahBlah, but
  203.  it always means the same - almost unique number belongs to file.
  204.  On Amiga side I could use GetUniqueID() from utility.library, but
  205.  it is available under OS3.0 and newer and, what is more important,
  206.  generates only 4294967295 unique numbers. That's all.
  207.  
  208.  
  209.  Bugs (eep...)
  210.  -------------
  211.  
  212.  Program doesn't recognize if name belongs to directory or to file and
  213.  treats all the same. For now, it also can't scan directories
  214.  recursively. Solution: do not create subdirs in drawer you want
  215.  SaveNames to process.
  216.  
  217.  There may appear some problems if you will have two files in the dir,
  218.  being in fact links to other file. In this case INode will be the
  219.  same. Solution: use proper file instead of its shadows.
  220.  
  221.  You must _not_ have file named 'WFMHFile.idx' in your drawer, because
  222.  while encoding/decoding it's written/read sequentially. So while
  223.  encoding it may be overwriten (but not if it is 1st file
  224.  in directory :). While decoding it will be skipped, because of
  225.  already opened (being in use) file with the same name. Solution:
  226.  rename your file :)
  227.  
  228.  On Amiga side SaveNames doesn't work when called from WB. If I find some
  229.  spare time I maybe add this, but I am not quite sure it's really needed.
  230.  
  231.  If you have transferred this archive from Unix account to your
  232.  machine via pc, you have probably noticed that few letters have been
  233.  eaten.. You should use... SaveNames to avoid it! :)
  234.  
  235.  Some older compilers requires the function to be declared in old C&R
  236.  style (see the source if you don't know what it's about). If you are
  237.  own such a compiler, simply uncommet the OLD_STYLE definition before
  238.  you start to compile the program.
  239.  
  240.  
  241.  Future plans (wow!)
  242.  -------------------
  243.  
  244.  If someone finds a reason to decode single files too, I will add this
  245.  feature on request, bacause it's easy to do... :)
  246.  
  247.  I also may add WB handling, but I don't think anybody needs this.
  248.  
  249.  Recursive directory scanning.
  250.  
  251.  
  252.  History (what has happen to the Sherlock Holmes in the past)
  253.  ------------------------------------------------------------
  254.  
  255.   * v1.0  -  Initial release
  256.              Worldwide distribution
  257.              SaveNames-mania....
  258.  
  259.   * v1.1  -  WARNING: Internal format of the 'WFMHFile.idx'
  260.              has been changed! Better decode all old stuff
  261.              before you install this release!
  262.  
  263.              Changes:
  264.  
  265.           -  LINUX and gcc differences and needs supported
  266.           -  Unnecessary %ld's replaced by %d's
  267.           -  SaveNames could not find the index file on Unix
  268.               side if its name was 'processed' by pc (see doc)
  269.  
  270.              Reported by Niklas Edmundsson
  271.  
  272.           -  Added old C&R function declaration for older compilers
  273.               (this feature is switchable and defaulty is off)
  274.           -  SaveNames will not remove 'WFMHFile.idx' index file
  275.               if restoring was not 100% successed
  276.  
  277.              Sugested by Konrad Dubiel
  278.  
  279.   * v1.2  -  Expand decoding mode added (see 'Technical Info').
  280.           -  Solved problems with names contain spaces (this was
  281.               the main reason I've changed the index file format).
  282.           -  SaveNames can now calculate number of disks you will
  283.               need to store contents of your dir on floppies
  284.               (both for Amiga and pc disks) and number of bytes
  285.               left free on the last diskiette.
  286.           -  New command '-C' ('-COUNT') added, which scans given
  287.               directory and counts total length of files and
  288.               floppy disk usage (while coding, those information
  289.               will also be shown).
  290.           -  Source slightly rewritten.
  291.  
  292.   * v1.3  -  Small code improvements (it's now even more portable :-)
  293.           -  Enforcer hit removed
  294.  
  295.   * v1.4  -  File splitting added.
  296.           -  Bug fix: Now doesn't lock up if you already have
  297.               WFMHFile.idx in the dir and want to CODE something.
  298.           -  Now statistics shows total size in KB or MB only
  299.              when needed (no more 0 KB etc).
  300.  
  301.   * v1.5  -  If a size of given file was multipler of specified
  302.              splitsize, an error was reported and no entry was
  303.              added to WFMHFile.idx for this file. Fixed.
  304.           -  Function div() not used any more (helps under SunOS 4).
  305.           -  Amiga version string added.
  306.           -  SunOS 4 direct support.
  307.  
  308.  
  309.  Author (it's me, it's me)
  310.  -------------------------
  311.  
  312.  Marcin Orlowski
  313.  ul. Radomska 38
  314.  71-002 Szczecin
  315.  Poland
  316.  
  317.  E-Mail: carlos@dedal.man.szczecin.pl
  318.  WWW   : http://www.szczecin.pl/~carlos
  319.  
  320.  FidoNet:       Marcin Orlowski@2:481/22.2
  321.  GlobalNet:     Marcin Orlowski@52:4800/6
  322.  
  323.  
  324.  Responsible for SaveNames v1.4+ is:
  325.  
  326.  Tadek Knapik
  327.  ul. Duza Gora 35/88
  328.  30-857 Krakow
  329.  Poland
  330.  
  331.  E-Mail: tadek@student.uci.agh.edu.pl
  332.  
  333.  Improving SaveNames from v1.3 to v1.4 (with the author's agreement) is
  334.  the first thing I've done in C (excluding K&R's Chapter 1 exercises :-)
  335.  so it may be somewhat strange kind of code. It WORKS, but you should
  336.  look at it if you're not very trusting person... :-)
  337.  
  338.  
  339. --------------------- C O M M E R C I A L    B R E A K --------------------
  340.  
  341.       ______ __   __
  342.      / ____//_/  / /            Find your way to the smallest & slowest
  343.     / /___ __   / /  __  __ ______ _____
  344.    /___  // /  / /  / / / // ____// .__/   BBS in central Europe !!!
  345.   ____/ // /_ / /_ / /_/ // __/_ / /
  346.  /_____//___//___/ \____//_____//_/           W.F.M.H. support
  347.                                                                  __
  348.                        ____       GlobalNET: 52:4800/6       __ / /
  349.   +48 91 540431       / __ \        FidoNET: 2:481/22.2     / / \/
  350.                      / / / /_____ ______ ______ _   _      / /   ______
  351.  24 Hours / Day     / / / // .__// ____// __  // \_/ \    /_/   / ____/
  352.                    / /_/ // /   / __/_ / __  // /__/ /   __    _\__  /
  353.  1200-19200 bps   /_____//_/   /_____//_/ /_//_/  /_/   /_/   /_____/
  354.  
  355.      Serving on A3000, 2CDTVs, 2A500+, 5 additional CD-ROMs on-line
  356.                For all Amigas, Macs, C64 and Spectrum fans
  357.